Proposal: Lead/Deputy maintainers, and PROJECT_STATUS.md#32
Conversation
- Add project-docs/roles/REPO-LEADERSHIP.md proposing Lead and Deputy Maintainer roles for active repositories. Includes responsibilities, selection criteria, lifecycle status linkage (active requires a named Lead; without one a repo is maintenance), and an emeritus/stepping-down policy for the per-repo roles. - Add PROJECT_STATUS.md defining lifecycle_status and owner_model values. Explicitly ties 'active' status to having a named_lead, and 'maintenance' to org_shared ownership, so the distinction between the two statuses is grounded in real staffing rather than just activity level.
hydrosquall
changed the title
|
|
||
| Emeritus Leads and Deputies retain community membership and remain welcome participants. They may return to a Lead or Deputy role through the normal nomination and approval process. | ||
|
|
||
| This per-repo emeritus process is separate from, and in addition to, the org-wide Maintainer emeritus process described in [GOVERNANCE.md](../GOVERNANCE.md). |
|
Thanks for putting this together @hydrosquall. I added my thumbs up as it seems like this doesn't add any extra work to people currently already acting as the core maintainers of specific repos and, if I understand correctly, it mostly to make things more explicit which I think can be helpful. |
domoritz
left a comment
domoritz
left a comment
There was a problem hiding this comment.
I like this a lot but it feels a bit more verbose than the other docs we have. I think after some compression I would feel more comfortable with having this as part of the official project docs
|
|
||
| ## Motivation | ||
|
|
||
| As the Vega ecosystem has grown across multiple (100+) repositories, it became harder to tell where maintenance capacity exists, which work is blocked, and who is coordinating review, triage, and release readiness for each repo. There was also not a clear path for sponsors or new contributors to identify who within the current volunteer team is both available and equipped to provide this kind of support. |
There was a problem hiding this comment.
I don't think we need this full documentation in the project docs. Let's keep the docs lightweight.
There was a problem hiding this comment.
A general tightening pass over the document may help to make it easier to comprehend.
There was a problem hiding this comment.
I thought it would be helpful context to post the motivation someplace to explain why we didn't cargo-cult the idea of adding leadership roles / that it was motivated by a specific problem (helping the project to pass on responsibility to maintainers who are not the original authors), but I agree with you in retrospect that we don't need that in git history. I'll do a pass, thanks for the close read.
|
|
||
| This document creates a lightweight Lead Maintainer role for repositories. The goal is to make coordination responsibility visible, reduce ambiguity, and improve contributor understanding of the level of support available for each Vega repository. | ||
|
|
||
| This proposal does not change existing admin or Steering Committee roles. It aims to address a gap in responsibilities for the existing Maintainer role. |
There was a problem hiding this comment.
We definitely need to make a pass to move over there what makes sense and reference the lead maintainer role there.
|
|
||
| A repository is considered **active** only when it has a named Lead Maintainer. A named Deputy Maintainer is strongly recommended to ensure continuity when the Lead is unavailable and to avoid PR freezes. | ||
|
|
||
| A repository that cannot sustain a named Lead — drawing instead from the shared maintainer pool — should be marked **maintenance** rather than active. This is not a judgment on the project's value; it is an honest signal about the level of dedicated coordination currently available. |
There was a problem hiding this comment.
How do we do this exactly? Do we use badges? Maybe something like https://gist.github.com/taiki-e/ad73eaea17e2e0372efb76ef6b38f17b
There was a problem hiding this comment.
We could use badges or plain text, I don't think it makes a difference. The maintenance badge status looks great to me.
The important part is for this metadata to be easily discoverable (definitely in the README.md above the fold maybe in the package.json too)
| ## Responsibilities | ||
|
|
||
| The Lead Maintainer is responsible for activities such as: | ||
|
|
||
| - being a point of contact for new contributors | ||
| - ensuring issues and PRs are labeled and routed on a regular basis | ||
| - ensuring contributors (of code or issues) are able to receive quality feedback | ||
| - identifying blocked or stale PRs | ||
| - making release blockers and release-readiness tasks visible | ||
| - routing contributor questions to the right place | ||
| - documenting major decisions publicly | ||
| - keeping the repo health status current | ||
| - escalating cross-repo/spec/API issues | ||
| - making the repo's need for additional maintainer, reviewer, docs, or triage capacity visible to the Steering Committee | ||
|
|
||
| ## Non-responsibilities | ||
|
|
||
| The Lead Maintainer is not expected to: | ||
|
|
||
| - personally fix each bug | ||
| - personally review each PR | ||
| - guarantee response times | ||
| - carry the repository alone | ||
| - accept new features without a maintenance path | ||
| - make unilateral breaking changes | ||
| - override maintainer consensus |
There was a problem hiding this comment.
These are great but feel a bit too vague to be part of the official governance docs. If we say "routing contributor questions to the right place" is a responsibility, I think it's hard to make this concrete. The governance docs (so far at least) are to me almost like laws we wrote which is why we carefully crafted them to be concise and concrete. This document differs a bit from the others (e.g. https://github.com/vega/.github/blob/main/project-docs/GOVERNANCE.md in that regard).
There was a problem hiding this comment.
I agree that the tone of this doc is off compared to the rest of GOVERNANCE.md . However, I also think it's worth being explicit about the ways in which accepting the responsibility of being a lead maintainer is different from being a a regular maintainer.
Some larger projects are very explicit about the roles/responsibilities of various sub-roles (such as triager, merger, releaser: https://www.djangoproject.com/foundation/teams/#releasers-team )
I also liked the efficiency of the Pandas / Matplotlib, which keep governance light, and use "workgroups" for more specialized collections of responsibilities that are not repo-specific
https://pandas.pydata.org/about/team.html#workgroups
Let me try to trim this down so we can get get an MVP merged, and work on something like a lead-maintainer guidebook as we iterate on our understanding of the role.
| | `experimental` | Exploratory work. APIs, scope, or long-term maintenance may change. | | ||
| | `maintenance` | Kept working, but limited new feature development. No named Lead; draws from the shared maintainer pool. | | ||
| | `deprecated` | Users should migrate elsewhere. A replacement should be listed where possible. | | ||
| | `archived` | Historical or read-only project. No support is expected. | |
There was a problem hiding this comment.
Archived is already something GitHub supports natively.
There was a problem hiding this comment.
I can modify this to make explicit that this status badge will be expressed through Github's "archived" feature rather than having to retroactively unarchive such repos just to update their README.md
|
|
||
| ## Responsibilities | ||
|
|
||
| The Lead Maintainer is responsible for activities such as: |
There was a problem hiding this comment.
| The Lead Maintainer is responsible for activities such as: | |
| The Lead Maintainer is responsible for: |
|
|
||
| - being a point of contact for new contributors | ||
| - ensuring issues and PRs are labeled and routed on a regular basis | ||
| - ensuring contributors (of code or issues) are able to receive quality feedback |
There was a problem hiding this comment.
| - ensuring contributors (of code or issues) are able to receive quality feedback | |
| - ensuring contributors (of code or issues) receive quality feedback |
| The Lead Maintainer is responsible for activities such as: | ||
|
|
||
| - being a point of contact for new contributors | ||
| - ensuring issues and PRs are labeled and routed on a regular basis |
There was a problem hiding this comment.
How regular? I liked our discussion about letting leads (generally, not just lead maintainers) set rules for their role themselves. We can leave it intentionally vague.
There was a problem hiding this comment.
I think the key motivation for this line to publicly advertise "on a regular basis" was to help the community (of users and contributors) understand the realistic bandwidth for a repo, it helps build the case for why sponsorship is necessary if the health of this repository is important to your line of work (be it research or industry).
For me the motivation for this line is that "a project benefits from lead maintainer who is transparent and willing to hold themselves to a standard about their availability", not "a specific frequency is needed for all maintainers".
| - being a point of contact for new contributors | ||
| - ensuring issues and PRs are labeled and routed on a regular basis | ||
| - ensuring contributors (of code or issues) are able to receive quality feedback | ||
| - identifying blocked or stale PRs |
There was a problem hiding this comment.
Maybe cut or say more concretely what to do after identifying those. Are lead maintainers expected to be admins?
There was a problem hiding this comment.
I don't think a lead maintainer has to be an admin as it require them to have org access to the whole Github organization. A lead maintainer just needs the ability to fully administrate their specific repository.
Let me work on trimming this section / having light suggestions for next steps on only the ones that stay.
3 participants
Motivation
As a pre-requisite to several changes related to building the community and project health around Vega (for code and non-code contributions alike), I'd like to propose updating the governance structure to recognize
Lead Maintainers.This idea was verbally presented and discussed at the May steering committee meeting
Changes
This PR proposes three governance additions for the Vega org.
1. Lead and Deputy Maintainer roles (
project-docs/roles/REPO-LEADERSHIP.md)A lightweight per-repository Lead Maintainer role to make coordination responsibility visible. The Lead is responsible for coordination health (triage routing, unblocking PRs, release-readiness visibility, escalation) , essentially a "DRI" for the open source project. A Deputy is strongly recommended to ensure continuity when the Lead is unavailable , but not required for a repo to have a Lead.
This does not change Admin or Steering Committee roles.
2. Active vs. maintenance status tied to staffing (
PROJECT_STATUS.md)A repository is
activeonly when it has a named Lead Maintainer. A repository drawing from the shared maintainer pool ismaintenance, regardless of activity level. This makes it straightforward for new contributors and supporting organizations to know which projects are currently active and may be good fits for contributing to, vs which projects could become active if someone was capable and willing to help maintain it.3. Emeritus policy for Lead/Deputy roles
I also propose an inactivity-based offboarding process scoped to the per-repo roles, separate from the org-wide Maintainer emeritus process. The inactivity window is 6 months scoped to the specific repository. Outreach is required before acting with a 30-day wait and 60-day deadline. If no replacement is found, the repo moves to
maintenance. Emeritus Leads and Deputy maintainers may return through the normal nomination process.Notes
I have a separate proposal around how to build automation around how to recruit and set new maintainers up for success, but I wanted to keep the initial document lightweight.
Given that Vega does not have a primary corporate sponsor, is intentionally lighter weight than the structure of more "federated" projects like K8s and Apache PMC projects.
I also based this proposal on discussions with @BridgeAR of the NodeJS TSC, the many contributors to the Github Open Source Guides for the advice on open source project structure, and writings from both Nadia Eghbal (Roads and Bridges) and Karl Fogel on Producing Open Source Software